home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / zsysvx.z / zsysvx
Encoding:
Text File  |  2002-10-03  |  10.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZSYSVX - use the diagonal pivoting factorization to compute the solution
  10.      to a complex system of linear equations A * X = B,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE ZSYSVX( FACT, UPLO, N, NRHS, A, LDA, AF, LDAF, IPIV, B, LDB,
  14.                         X, LDX, RCOND, FERR, BERR, WORK, LWORK, RWORK, INFO )
  15.  
  16.          CHARACTER      FACT, UPLO
  17.  
  18.          INTEGER        INFO, LDA, LDAF, LDB, LDX, LWORK, N, NRHS
  19.  
  20.          DOUBLE         PRECISION RCOND
  21.  
  22.          INTEGER        IPIV( * )
  23.  
  24.          DOUBLE         PRECISION BERR( * ), FERR( * ), RWORK( * )
  25.  
  26.          COMPLEX*16     A( LDA, * ), AF( LDAF, * ), B( LDB, * ), WORK( * ), X(
  27.                         LDX, * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      ZSYSVX uses the diagonal pivoting factorization to compute the solution
  44.      to a complex system of linear equations A * X = B, where A is an N-by-N
  45.      symmetric matrix and X and B are N-by-NRHS matrices.
  46.  
  47.      Error bounds on the solution and a condition estimate are also provided.
  48.  
  49.  
  50. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  51.      The following steps are performed:
  52.  
  53.      1. If FACT = 'N', the diagonal pivoting method is used to factor A.
  54.         The form of the factorization is
  55.            A = U * D * U**T,  if UPLO = 'U', or
  56.            A = L * D * L**T,  if UPLO = 'L',
  57.         where U (or L) is a product of permutation and unit upper (lower)
  58.         triangular matrices, and D is symmetric and block diagonal with
  59.         1-by-1 and 2-by-2 diagonal blocks.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      2. If some D(i,i)=0, so that D is exactly singular, then the routine
  75.         returns with INFO = i. Otherwise, the factored form of A is used
  76.         to estimate the condition number of the matrix A.  If the
  77.         reciprocal of the condition number is less than machine precision,
  78.         INFO = N+1 is returned as a warning, but the routine still goes on
  79.         to solve for X and compute error bounds as described below.
  80.  
  81.      3. The system of equations is solved for X using the factored form
  82.         of A.
  83.  
  84.      4. Iterative refinement is applied to improve the computed solution
  85.         matrix and calculate error bounds and backward error estimates
  86.         for it.
  87.  
  88.  
  89. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  90.      FACT    (input) CHARACTER*1
  91.              Specifies whether or not the factored form of A has been supplied
  92.              on entry.  = 'F':  On entry, AF and IPIV contain the factored
  93.              form of A.  A, AF and IPIV will not be modified.  = 'N':  The
  94.              matrix A will be copied to AF and factored.
  95.  
  96.      UPLO    (input) CHARACTER*1
  97.              = 'U':  Upper triangle of A is stored;
  98.              = 'L':  Lower triangle of A is stored.
  99.  
  100.      N       (input) INTEGER
  101.              The number of linear equations, i.e., the order of the matrix A.
  102.              N >= 0.
  103.  
  104.      NRHS    (input) INTEGER
  105.              The number of right hand sides, i.e., the number of columns of
  106.              the matrices B and X.  NRHS >= 0.
  107.  
  108.      A       (input) COMPLEX*16 array, dimension (LDA,N)
  109.              The symmetric matrix A.  If UPLO = 'U', the leading N-by-N upper
  110.              triangular part of A contains the upper triangular part of the
  111.              matrix A, and the strictly lower triangular part of A is not
  112.              referenced.  If UPLO = 'L', the leading N-by-N lower triangular
  113.              part of A contains the lower triangular part of the matrix A, and
  114.              the strictly upper triangular part of A is not referenced.
  115.  
  116.      LDA     (input) INTEGER
  117.              The leading dimension of the array A.  LDA >= max(1,N).
  118.  
  119.      AF      (input or output) COMPLEX*16 array, dimension (LDAF,N)
  120.              If FACT = 'F', then AF is an input argument and on entry contains
  121.              the block diagonal matrix D and the multipliers used to obtain
  122.              the factor U or L from the factorization A = U*D*U**T or A =
  123.              L*D*L**T as computed by ZSYTRF.
  124.  
  125.              If FACT = 'N', then AF is an output argument and on exit returns
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              the block diagonal matrix D and the multipliers used to obtain
  141.              the factor U or L from the factorization A = U*D*U**T or A =
  142.              L*D*L**T.
  143.  
  144.      LDAF    (input) INTEGER
  145.              The leading dimension of the array AF.  LDAF >= max(1,N).
  146.  
  147.      IPIV    (input or output) INTEGER array, dimension (N)
  148.              If FACT = 'F', then IPIV is an input argument and on entry
  149.              contains details of the interchanges and the block structure of
  150.              D, as determined by ZSYTRF.  If IPIV(k) > 0, then rows and
  151.              columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1
  152.              diagonal block.  If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then
  153.              rows and columns k-1 and -IPIV(k) were interchanged and D(k-
  154.              1:k,k-1:k) is a 2-by-2 diagonal block.  If UPLO = 'L' and IPIV(k)
  155.              = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were
  156.              interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
  157.  
  158.              If FACT = 'N', then IPIV is an output argument and on exit
  159.              contains details of the interchanges and the block structure of
  160.              D, as determined by ZSYTRF.
  161.  
  162.      B       (input) COMPLEX*16 array, dimension (LDB,NRHS)
  163.              The N-by-NRHS right hand side matrix B.
  164.  
  165.      LDB     (input) INTEGER
  166.              The leading dimension of the array B.  LDB >= max(1,N).
  167.  
  168.      X       (output) COMPLEX*16 array, dimension (LDX,NRHS)
  169.              If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X.
  170.  
  171.      LDX     (input) INTEGER
  172.              The leading dimension of the array X.  LDX >= max(1,N).
  173.  
  174.      RCOND   (output) DOUBLE PRECISION
  175.              The estimate of the reciprocal condition number of the matrix A.
  176.              If RCOND is less than the machine precision (in particular, if
  177.              RCOND = 0), the matrix is singular to working precision.  This
  178.              condition is indicated by a return code of INFO > 0.
  179.  
  180.      FERR    (output) DOUBLE PRECISION array, dimension (NRHS)
  181.              The estimated forward error bound for each solution vector X(j)
  182.              (the j-th column of the solution matrix X).  If XTRUE is the true
  183.              solution corresponding to X(j), FERR(j) is an estimated upper
  184.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  185.              divided by the magnitude of the largest element in X(j).  The
  186.              estimate is as reliable as the estimate for RCOND, and is almost
  187.              always a slight overestimate of the true error.
  188.  
  189.      BERR    (output) DOUBLE PRECISION array, dimension (NRHS)
  190.              The componentwise relative backward error of each solution vector
  191.              X(j) (i.e., the smallest relative change in any element of A or B
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))                                                          ZZZZSSSSYYYYSSSSVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.              that makes X(j) an exact solution).
  207.  
  208.      WORK    (workspace/output) COMPLEX*16 array, dimension (LWORK)
  209.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  210.  
  211.      LWORK   (input) INTEGER
  212.              The length of WORK.  LWORK >= 2*N, and for best performance LWORK
  213.              >= N*NB, where NB is the optimal blocksize for ZSYTRF.
  214.  
  215.              If LWORK = -1, then a workspace query is assumed; the routine
  216.              only calculates the optimal size of the WORK array, returns this
  217.              value as the first entry of the WORK array, and no error message
  218.              related to LWORK is issued by XERBLA.
  219.  
  220.      RWORK   (workspace) DOUBLE PRECISION array, dimension (N)
  221.  
  222.      INFO    (output) INTEGER
  223.              = 0: successful exit
  224.              < 0: if INFO = -i, the i-th argument had an illegal value
  225.              > 0: if INFO = i, and i is
  226.              <= N:  D(i,i) is exactly zero.  The factorization has been
  227.              completed but the factor D is exactly singular, so the solution
  228.              and error bounds could not be computed. RCOND = 0 is returned.  =
  229.              N+1: D is nonsingular, but RCOND is less than machine precision,
  230.              meaning that the matrix is singular to working precision.
  231.              Nevertheless, the solution and error bounds are computed because
  232.              there are a number of situations where the computed solution can
  233.              be more accurate than the value of RCOND would suggest.
  234.  
  235. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  236.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  237.  
  238.      This man page is available only online.
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.